\" t
.\" ** The above line should force tbl to be a preprocessor **
.\" Man page for vncserver
.\"
.\" Copyright (C) 1998 Marcus.Brinkmann@ruhr-uni-bochum.de
.\" Copyright (C) 2000, opal@debian.org
.\" Copyright (C) 2000, 2001 Red Hat, Inc.
.\" Copyright (C) 2001, 2002 Constantin Kaplinsky
.\" Copyright (C) 2005-2006 Sun Microsystems, Inc.
.\" Copyright (C) 2010-2013, 2015-2018, 2020, 2022 D. R. Commander
.\"
.\" You may distribute under the terms of the GNU General Public
.\" License as specified in the file LICENCE.TXT that comes with the
.\" TightVNC distribution.
.\"
.TH vncserver 1 "December 2020" "" "TurboVNC"
.SH NAME
vncserver \- a wrapper to launch the TurboVNC Server
.SH SYNOPSIS
.nh
.ad l
\fBvncserver\fR
[:\fIdisplay\fR] [\-geometry\ \fIwidth\fRx\fIheight\fR]
[\-geometry\ \fIW0\fRx\fIH0\fR+\fIX0\fR+\fIY0\fR[,\fIW1\fRx\fIH1\fR+\fIX1\fR+\fIY1\fR,...,\fIWn\fRx\fIHn\fR+\fIXn\fR+\fIYn\fR]]
[\-depth\ \fIdepth\fR] [\-pixelformat\ rgb\fINNN\fR|bgr\fINNN\fR]
[\-fp\ \%\fIfont\-path\fR] [\-name\ \fIdesktop\-name\fR]
[\-novnc \fInovnc\-dir\fR] [\-otp]
[\-x509cert\ \fIcert\fR] [\-x509key\ \fIkey\fR] [\-fg] [\-noautokill]
[\-noxstartup] [\-xstartup\ \fIscript\fR] [\-wm \fIwindow-manager\fR] [\-vgl]
[\-log\ \fIfile\fR]
\%[\fIXvnc\-options\fR...]
.ad
.hy
.TP
\fBvncserver\fR \-kill :\fIdisplay\fR
.TP
\fBvncserver\fR \-list
.TP
\fBvncserver\fR \-help
.SH DESCRIPTION
\fBvncserver\fR is a wrapper script for \fBXvnc\fR, the VNC (Virtual Network
Computing) X server. Xvnc provides all of the capabilities of a standard X
server, but it does not connect to a physical display. Instead, \fBXvnc\fR
creates a virtual X display that you can view or control remotely using a VNC
viewer.
.SH OPTIONS
You can add \fBXvnc\fR options to the \fBvncserver\fR command line. They will be
passed through to Xvnc without modification. The options provided by
\fBvncserver\fR itself are as follows:
.TP
\fB:\fR\fIdisplay\fR
The X display number that Xvnc should occupy. If omitted, the next free display number
is used.
.TP
\fB\-geometry\fR \fIwidth\fR\fBx\fR\fIheight\fR
Set width and height of the virtual X display.
.TP
\fB\-geometry\fR \fIW0\fRx\fIH0\fR+\fIX0\fR+\fIY0\fR[,\fIW1\fRx\fIH1\fR+\fIX1\fR+\fIY1\fR,...,\fIWn\fRx\fIHn\fR+\fIXn\fR+\fIYn\fR]
Set multi-screen geometry of the virtual X display.  Wi and Hi are the width
and height of Screen i, and Xi and Yi specify the offset of Screen i relative
to the origin.  The total width and height are determined by the bounding box
of all screens.
.TP
\fB\-depth\fR \fIdepth\fR
Set the color depth of the virtual X display, in bits per pixel. Must
be a value between 8 and 32.
.TP
\fB\-pixelformat\fR \fBrgb\fR\fINNN\fR|\fBbgr\fR\fINNN\fR
Specify the pixel format of the virtual X display. Xvnc can use any pixel
format you choose, but if this pixel format does not match the pixel format
of the display on which vncviewer is running, then Xvnc will perform pixel
format conversion prior to sending images to vncviewer. This can slow
performance. The default pixel format, rgb888, is equivalent to BGRA on little
endian systems or ARGB on big endian systems.  A pixel format of bgr888 is
equivalent to RGBA on little endian systems or ABGR on big endian systems.
.TP
\fB\-fp\fR \fIfont-path\fR
The vncserver script will normally examine your system to figure out where it
stores its X11 fonts and then generate an appropriate font path for Xvnc based
on this.  If your system stores its X11 fonts in a location that vncserver does
not know about, however, then this may fail.  In that case, vncserver will then
try to contact the local X Font Server (xfs) on port 7100.  Not all systems
have xfs installed and running, so this may fail as well.  In that case, you
can manually specify a font path by using the -fp argument to vncserver.

If you prefer to use the X Font Server by default rather than a static font
path, then you can run

{TurboVNC_directory}/bin/vncserver -fp unix/:7100

on Linux systems or

{TurboVNC_directory}/bin/vncserver -fp inet/:7100

on Solaris systems.
.TP
\fB\-name\fR \fIstring\fR
This specifies the name of the desktop.
.TP
\fB-novnc\fR \fInovnc\-dir\fR
Automatically start a simple web server that serves up noVNC (an
HTML 5/JavaScript VNC viewer) from directory \fInovnc\-dir\fR when starting a
TurboVNC session.  \fBvncserver\fR tracks the process ID of the noVNC web
server and automatically kills that process along with the TurboVNC session.
noVNC works in any web browser (including on mobile devices), but since it only
supports VNC Password authentication, it is strongly recommended that it be
used only with one-time passwords unless the connections are encrypted (see
\fB-x509cert\fR and \fB-x509key\fR below.)  The performance of noVNC will
generally be much less than that of the TurboVNC Viewer.
.TP
\fB\-otp\fR
If the One-Time Password authentication method is enabled and permitted in
Xvnc, then this generates an initial one-time password and prints it to the
console prior to starting Xvnc.
.TP
\fB\-x509cert\fR \fIcert\fR
Specify the X.509 signed certificate file (in PEM format) to use with X.509
encryption, the built-in WebSocket proxy, and the noVNC web server.  If this
argument is specified, then it is passed to Xvnc and the noVNC web server.
Otherwise, the \fBvncserver\fR script passes a default value of
$vncUserDir/x509_cert.pem.
.TP
\fB\-x509key\fR \fIkey\fR
Specify the X.509 private key file (in PEM format) to use with X.509
encryption, the built-in WebSocket proxy, and the noVNC web server.  If this
argument is specified, then it is passed to Xvnc and the noVNC web server.
Otherwise, the \fBvncserver\fR script passes a default value of
$vncUserDir/x509_private.pem.
.TP
\fB\-fg\fR
Runs the X startup script as a foreground process.  This has two effects:
(1) The TurboVNC session can be aborted with CTRL-C, and (2) the TurboVNC
session will exit as soon as the user logs out of the window manager in the
session.  This may be necessary when launching TurboVNC from within certain
grid computing environments.
.TP
\fB\-noautokill\fR
Normally, \fBvncserver\fR automatically kills the TurboVNC session when the
X startup script exits (which, in most cases, means that the session will be
killed automatically whenever the user logs out of the window manager running
in the session.)  This option disables that behavior.
.TP
\fB\-noxstartup\fR
Do not run the default X startup script (xstartup.turbovnc) after launching
Xvnc.  This option allows you to manually start a window manager in your
TurboVNC session or to run a full-screen application without a window manager.
.TP
\fB\-xstartup\fR \fIscript\fR
Run a custom X startup script, instead of the default X startup script, after
launching Xvnc.  This is useful in conjunction with the \fB-fg\fR option, since
it allows for running a full-screen application (such as a game or a
virtualization solution) in TurboVNC without a window manager and causes the
TurboVNC session to terminate whenever the application exits.
.TP
\fB-wm\fR \fIwindow-manager\fR
This sets the value of the \fBTVNC_WM\fR environment variable to
\fIwindow-manager\fR.  The default X startup script will launch the window
manager specified in the \fBTVNC_WM\fR environment variable, if it is set and
a corresponding session desktop file exists under /usr/share/xsessions.
.TP
\fB\-vgl\fR
This sets an environment variable (\fBTVNC_VGL\fR) to 1, and the default
X startup script will launch the window manager using VirtualGL if that
environment variable is set.  More specifically, if \fBTVNC_VGL\fR is set, then
the default X startup script will launch the window manager using a command
specified in another environment variable (\fBTVNC_VGLRUN\fR.)  The default
value of \fBTVNC_VGLRUN\fR is "vglrun +wm", but users can override that
environment variable in order to pass additional arguments to vglrun, to
specify the full path of vglrun, or to use another command to launch the window
manager.
.TP
\fB\-log\fR  \fIfile\fR
Redirect the output of Xvnc to \fIfile\fR, rather than to
$vncUserDir/.vnc/{hostname}{display}.log.
.TP
\fB\-kill\fR \fB:\fR\fIdisplay\fR
Stops the VNC session that is currently running on the specified display.
.TP
\fB\-list\fR
Lists the display numbers and process ID's of all VNC sessions that are
currently running under your account on this host.
.TP
\fB\-help\fR
Prints a brief list of command line options
.SH EXAMPLES
.TP
\fBvncserver\fR
Starts \fBXvnc\fR on the next available display and uses suitable
defaults.
.TP
\fBvncserver\fR \fI:1\fR
Starts \fBXvnc\fR on display :1.
.TP
\fBvncserver\fR -geometry \fI1024x768 :1\fR
Starts \fBXvnc\fR on display :1 with desktop size of 1024x768 pixels.
.TP
\fBvncserver\fR -kill \fI:1\fR
Shuts down the VNC session running on display :1.
.SH FILES
.TP
@CMAKE_INSTALL_FULL_SYSCONFDIR@/turbovncserver.conf
System-wide configuration file for the TurboVNC Server.
.TP
$HOME/.vnc/turbovncserver.conf
User configuration file for the TurboVNC Server. Settings in this file
override the system-wide configuration.
.SH SEE ALSO
\fBXvnc\fR(1), \fBvncviewer\fR(1), \fBvncpasswd\fR(1), \fBvncconnect\fR(1)
.SH AUTHORS
VNC was originally developed at AT&T Laboratories Cambridge. TightVNC
additions were implemented by Constantin Kaplinsky. TurboVNC, based
on TightVNC, is provided by The VirtualGL Project. Many other people
participated in development, testing and support.

\fBMan page authors:\fR
.br
Marcus Brinkmann <Marcus.Brinkmann@ruhr-uni-bochum.de>,
.br
Tim Waugh <twaugh@redhat.com>,
.br
Constantin Kaplinsky <const@tightvnc.com>
.br
D. R. Commander <information@turbovnc.org>
